<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.10"/>
<title>iomodule: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="HTML_custom.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="xlogo_bg.gif"/></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">iomodule
   </div>
   <div id="projectbrief">Xilinx SDK Drivers API Documentation</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.10 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Overview</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="globals.html"><span>APIs</span></a></li>
      <li><a href="files.html"><span>File&#160;List</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">iomodule Documentation</div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The Xilinx IO Module driver component. This component supports the IO Module. The IO Module provides: </p><ol>
<li>
Universal Asynchronous Receiver Transmitter (UART) </li>
<li>
Fixed Interval Timer (FIT) </li>
<li>
Programmable Interval Timer (PIT) </li>
<li>
General Purpose Output (GPO) </li>
<li>
General Purpose Input (GPI) </li>
<li>
Interrupt controller (INTC) </li>
<li>
IO bus (IO) </li>
</ol>
<p><b>Universal Asynchronous Receiver Transmitter (UART):</b> This UART is a minimal hardware implementation with minimal features. Most of the features, including parity, and number of data bits are only configurable when the hardware device is built, rather than at run time by software. The UART has an internal baud rate generator that is clocked at a specified input clock frequency. The baud rate can either be fixed, or programmable. Not all programmed baud rates can be generated from some clock frequencies. The requested baud rate is checked using the provided clock for the system, and checked against the acceptable error range. An error may be returned from some functions indicating the baud rate was in error because it could not be generated.</p>
<p>The device has support for interrupts: a transmit interrupt, a receive interrupt, and an error interrupt. The interrupts are individually configurable when the hardware device is built.</p>
<p>The driver defaults to no interrupts at initialization such that interrupts must be enabled if desired. An interrupt is generated when the transmitter transitions from having data to being empty, when any data is contained in the receive register, or when an error occurs in received data.</p>
<p>In order to use interrupts, it's necessary for the user to connect the driver interrupt handler, XIOModule_InterruptHandler, to the interrupt system of the application. This function does not save and restore the processor context such that the user must provide it. Send and receive handlers may be set for the driver such that the handlers are called when transmit and receive interrupts occur. The handlers are called from interrupt context and are designed to allow application specific processing to be performed.</p>
<p>The functions, XIOModule_Send and XIOModule_Recv, are provided in the driver to allow data to be sent and received. They are designed to be used in polled or interrupt modes.</p>
<p>The driver provides a status for each received byte indicating any parity frame or overrun error. The driver provides statistics which allow visibility into these errors.</p>
<p><b>Fixed Interval Timer (FIT):</b> The fixed interval timer supports the following features:</p><ul>
<li>Interrupt driven mode</li>
</ul>
<p>The timer has a hardware programmed time period, which can be configured to cause a periodic interrupt. The driver only provides the ability to handle such interrupts.</p>
<p><b>Programmable Interval Timer (PIT):</b> The programmable interval timer supports the following features:</p><ul>
<li>Polled mode</li>
<li>Interrupt driven mode</li>
<li>Enabling and disabling</li>
<li>Automatic reload</li>
</ul>
<p>The timer operates in compare mode. The timer always counts down.</p>
<p>Compare mode is typically used for creating a single time period or multiple repeating time periods in the auto reload mode, such as a periodic interrupt. When started, the timer loads an initial value, referred to as the load value, into the timer and starts counting down. The timer expires when it rolls under. An external Output signal may be configured such that a pulse is generated with this signal when it rolls under.</p>
<p>The timer can be configured to cause an interrupt when the count reaches zero. An external output is also toggled when the count reaches zero.</p>
<p><b>Interrupts</b></p>
<p>It is the responsibility of the application to connect the interrupt handler of the timer to the interrupt source. The interrupt handler function, XIOModule_InterruptHandler, is visible such that the user can connect it to the interrupt source. Note that this interrupt handler does not provide interrupt context save and restore processing, the user must perform this processing.</p>
<p>The driver services interrupts and passes timeouts to the upper layer software through callback functions. The upper layer software must register its callback functions during initialization. The driver requires callback functions for timers.</p>
<p><b>General Purpose Output (GPO):</b> The GPO has support for up to 32 I/O discrete outputs for each channel (128 bits total).</p>
<p><b>IO Bus (IO):</b> The IO Bus provides a generic mechanism to extend the IO Module functionality by providing a memory mapped IO area. Reading and writing of byte, halfword and word data is provided.</p>
<p><b>General Purpose Input (GPI):</b> The GPI has support for up to 32 I/O discrete outputs for each channel (128 bits total). An interrupt can be generated when any bit in a GPI changes.</p>
<p><b>Interrupt controller (INTC):</b> The interrupt controller driver uses the idea of priority for the various handlers. Priority is an integer within the range of 0 and 31 inclusive with 0 being the highest priority interrupt source.</p>
<p>The Xilinx interrupt controller supports the following features:</p>
<ul>
<li>specific individual interrupt enabling/disabling</li>
<li>specific individual interrupt acknowledging</li>
<li>attaching specific callback function to handle interrupt source</li>
<li>master enable/disable</li>
<li>single callback per interrupt or all pending interrupts handled for each interrupt of the processor</li>
</ul>
<p>The acknowledgement of the interrupt within the interrupt controller is selectable, either prior to the device's handler being called or after the handler is called. This is necessary to support interrupt signal inputs which are either edge or level signals. Edge driven interrupt signals require that the interrupt is acknowledged prior to the interrupt being serviced in order to prevent the loss of interrupts which are occurring extremely close together. A level driven interrupt input signal requires the interrupt to acknowledged after servicing the interrupt to ensure that the interrupt only generates a single interrupt condition.</p>
<p>Details about connecting the interrupt handler of the driver are contained in the source file specific to interrupt processing, <a class="el" href="xiomodule__intr_8c.html">xiomodule_intr.c</a>.</p>
<p>This driver is intended to be RTOS and processor independent. It works with physical addresses only. Any needs for dynamic memory management, threads or thread mutual exclusion, virtual memory, or cache control must be satisfied by the layer above this driver.</p>
<p><b>Interrupt Vector Tables</b></p>
<p>The interrupt vector table for each interrupt controller device is declared statically in <a class="el" href="xiomodule__g_8c.html">xiomodule_g.c</a> within the configuration data for each instance. The device ID of the interrupt controller device is used by the driver as a direct index into the configuration data table - to retrieve the vector table for an instance of the interrupt controller. The user should populate the vector table with handlers and callbacks at run-time using the <a class="el" href="group__iomodule__v2__2.html#ga65efd62e9193f589aa82dfa26fc90142" title="Makes the connection between the Id of the interrupt source and the associated handler that is to run...">XIOModule_Connect()</a> and <a class="el" href="group__iomodule__v2__2.html#ga241c2c08f867ee4d03e96248c4a133da" title="Updates the interrupt table with the Null Handler and NULL arguments at the location pointed at by th...">XIOModule_Disconnect()</a> functions.</p>
<p>Each vector table entry corresponds to a device that can generate an interrupt. Each entry contains an interrupt handler function and an argument to be passed to the handler when an interrupt occurs. The tools default this argument to the base address of the interrupting device. Note that the device driver interrupt handlers given in this file do not take a base address as an argument, but instead take a pointer to the driver instance. This means that although the table is created statically, the user must still use <a class="el" href="group__iomodule__v2__2.html#ga65efd62e9193f589aa82dfa26fc90142" title="Makes the connection between the Id of the interrupt source and the associated handler that is to run...">XIOModule_Connect()</a> when the interrupt handler takes an argument other than the base address. This is only to say that the existence of the static vector tables should not mislead the user into thinking they no longer need to register/connect interrupt handlers with this driver.</p>
<p>With fast interrupts enabled, the <a class="el" href="group__iomodule__v2__2.html#ga41e9fc5bdcbf29ff8675104fdef91697" title="Makes the connection between the Id of the interrupt source and the associated handler that is to run...">XIOModule_ConnectFastHandler()</a> function should be used instead of <a class="el" href="group__iomodule__v2__2.html#ga65efd62e9193f589aa82dfa26fc90142" title="Makes the connection between the Id of the interrupt source and the associated handler that is to run...">XIOModule_Connect()</a>. Note that the function pointer parameter Handler, must be a declared with the fast_interrupt attribute:</p>
<p>void Handler() __attribute__((fast_interrupt));</p>
<p>The routine defined by <a class="el" href="group__iomodule__v2__2.html#ga65efd62e9193f589aa82dfa26fc90142" title="Makes the connection between the Id of the interrupt source and the associated handler that is to run...">XIOModule_Connect()</a> can be used by setting normal interrupt mode, using <a class="el" href="group__iomodule__v2__2.html#gab4ddcaf38d655ca70d916c1d5ba96240" title="Sets the normal interrupt mode for the specified interrupt in the Interrupt Mode Register, by resetting the vector to (BaseVector & 0xFFFFFF80) | 0x10 and selecting normal mode. ">XIOModule_SetNormalIntrMode()</a>.</p>
<dl class="section note"><dt>Note</dt><dd></dd></dl>
<p>This API utilizes 32 bit I/O to the registers. With less than 32 bits, the unused bits from registers are read as zero and written as don't cares.</p>
<pre>
MODIFICATION HISTORY:</pre><pre>Ver   Who  Date     Changes
----- ---- -------- -------------------------------------------------------
1.00a sa   07/15/11 First release
1.01a sa   04/10/12 Updated with fast interrupt
1.02a sa   07/25/12 Updated with GPI interrupts and programmable baudrate
2.0   adk  19/12/13 Updated as per the New Tcl API's
2.1   bss  05/02/14 Added PitMask in <a class="el" href="struct_x_i_o_module___config.html" title="This typedef contains configuration information for the device. ">XIOModule_Config</a>.(CR #794167)
2.2	nsk  07/21/15 Updated iomodule_define_vector_table by removing
	      absoluted hsi commands like xget_handle.CR#865544.
	      modified generate proc to get canonical defintions
	      in xparameters.h
2.2   nsk  08/06/15 Updated XIOModule_Uart_InterruptHandler function
	      in <a class="el" href="xiomodule__uart__intr_8c.html">xiomodule_uart_intr.c</a> file to read Status register
	      instead of reading Interrupt Pending register.
	      (CR #862715).
2.2	nsk  08/07/15 Updated iomodule_define_vector_table in iomodule.tcl
	      to handle External vector interrupts.(CR #871572)
2.2	nsk  08/19/15 Modifed iomodule_define_vector_table in iomodule.tcl
	      to handle,if iomodule doesn't have interrupts enabled
	      (CR #876507).
2.2	nsk  09/02/15 Modified iomodule_define_vector_table in iomodule.tcl
	      when no external interrupts are used.(CR #878782)</pre><pre></pre> </div></div><!-- contents -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Copyright &copy; 2015 Xilinx Inc. All rights reserved.</li>
  </ul>
</div>
</body>
</html>
